home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1995 October / EnigmA AMIGA RUN 01 (1995)(G.R. Edizioni)(IT)[!][issue 1995-10][Aminet 7].iso / Aminet / comm / fido / FQUERY.lha / DOCS / FQ.doc next >
Text File  |  1995-04-20  |  18KB  |  404 lines
  1. $VER: FQ doc File Query and Search Utility Robert Williamson 00.55.75
  2.  
  3.     FQuery, FQueryM, FQueryP, FQscan, FQCheckList and FQFixList are all
  4.       Copyright (C) 1995 Robert Williamson
  5.     FQsearch was written for FQuery and is
  6.       Copyright (C) 1995 Fredric Morin
  7.  
  8.     KeyFiles are not to be redistributed.
  9.  
  10.     This  program  is  distributed  in the hope that it will be useful, but
  11.     WITHOUT   ANY   WARRANTY;   without   even   the  implied  warranty  of
  12.     MERCHANTABILITY  or  FITNESS  FOR  A  PARTICULAR  PURPOSE. 
  13.  
  14.     What it does:
  15.     
  16.     In  1991,  the  msdos  program ALLFIX, by Harald Harms,
  17.         "introduced the idea of searching for files via echomail. 
  18.          The  term applied to this function  is 'FileFind'.  The
  19.          FileFind system allows BBS USERS to search for files by
  20.          placing  a message to 'ALLFIX' and wait for a reply.
  21.          Each BBS system, running an  ALLFIX compatible FileFind
  22.          processor, will reply  to that user if there  any files
  23.          matching their requested  filespec."
  24.                     Quote from ALLFIX.DOC v4.20 by Harald Harms
  25.  
  26.     FQuery  IS  the  Complete  FileFind  system for the Amiga, with ALL the
  27. features  of  AllFix  and  many  more.   FQuery processes echomail messages
  28. addressed  to  FQuery, FileFind or AllFix and NetMail messages addressed to
  29. FQuery.   It  examines  and parses the subject field for search queries and
  30. netmail commands and posts a response of any matches found.
  31.  
  32.     FQuery is available in versions for either MSG base (FQueryM) or Packet
  33. scanning (FqueryP).
  34.  
  35.     See FQ.readme for list of features and technical compliance.
  36.  
  37.     The FileList:
  38.  
  39.     FQuery expects that file entries in your filelist start in column 2, in
  40. other  words,  each  filename is preceeded with a space.  FQuery will treat
  41. ALL  text lines that are preceeded with a single space as a file entry.  It
  42. will  ignore lines that have a character in column 1 or are not description
  43. continuation  lines as defined by the DESC_NUM and DESC_COL entries in your
  44. config.
  45.  
  46.     The  utility  FQCheckList  can  be used to scan your filelist.  It will
  47. output  some  statistics  with  which you may determine if your filelist is
  48. compliant with FQuery requirements.  It takes as arguments the fullpathname
  49. of  your  filelist,  the  start column of the file description and the word
  50. number in the line of the description.
  51.  
  52.         FQCheckList fullpathfilelist DESC_COL DESC_NUM
  53.  
  54.     Another  method  to  test  for  filelist compliance is to issue the
  55.   commands:
  56.  
  57.         SetEnv FQSEARCH DESC_COL-1,DESC_NUM ;use the actual values
  58.                                           ;not the variable names    
  59.                                           ;comma MUST be included
  60.  
  61.         FQsearch FullPathNameOfFileList #? -f ; 'f' MUST be lowercase
  62.  
  63.    The output should display all the file entries from your filelist,
  64.   properly formatted.
  65.  
  66.         If your filelist is non-compliant, the utility FQFixList can be
  67. used to attempt to make a compliant one. The arguments are as follows:
  68.  
  69.    FQFixList inputfile outputfile columns offset fancy
  70.      columns = number of columns in a file entry
  71.      offset  = character position where description starts
  72.      fancy   = characters which appear in col 1 of lines that have
  73.                the same number of columns as a file entry
  74.  
  75.     For example:
  76.         To convert a Cnet filelist produced by:
  77.         TUCFGII v2.5 By Shawn McNeece @1:104/535 
  78.  
  79.             FQFixList filelist newfilelist 5 38 +|
  80.  
  81.         The new DESC_COL value will be 39.
  82.  
  83.         To convert an AmiNet Index:
  84.  
  85.             FQFixList index newfilelist 5 42 |
  86.  
  87.         The new DESC_COL value will be 43.
  88.     
  89.     Be SURE to change DESC_COL in FQ.cfg.
  90.     
  91.  
  92.     Configuration:
  93.  
  94.     Configuration options allow for:
  95.         - definition of echotag, echopath, site address, sitename, inport
  96.           command and both import and export paths for each echo.
  97.         - definition of echo-specific exclusion parameters for message age,
  98.           description, filespec and keyword lengths and disallowed keywords
  99.         - exclusion of locally generated FQuery messages from processing
  100.         - backup of packets created.
  101.         - definition of progress window and public screen
  102.         - definition of site-specific information to be included in
  103.           messages.
  104.         - sending ABOUT file via netmail 
  105.         - sending NEWFILES file via netmail
  106.         - sending query response via netmail
  107.  
  108.         in addition, for the packet scanning version of FQuery:
  109.         - sites from which to accept packets for scanning
  110.         - list of echos to process
  111.         - output filename
  112.         - list of zones and domains
  113.  
  114.     Usage:
  115.  
  116.         (Both PKT and MSG versions)
  117.  
  118.         FQuery ?                     Displays FQuery usage.
  119.  
  120.         FQuery SHOW                  Displays the current configuration.
  121.  
  122.         FQuery REPORT <tagname>      Displays an echo configuration report.
  123.  
  124.         FQuery TEST n subject        Tests the configuration of echo n and
  125.                                      searchs for the subject specfied. 
  126.                                      If n=0, the DEFAULTS will be used.   
  127.                                      Displays the list of matches found and
  128.                                      also writes it to T:FQ.result.
  129.                                         
  130.  
  131.       EchoMail: (MSG version ONLY)
  132.  
  133.         FQuery SCAN                  Scans all defined EchoMail message
  134.                                      bases.
  135.         FQuery RESCAN n              ReScans EchoMail message base defined
  136.                                      by index n.      
  137.         FQuery REPROC n              ReProcesses EchoMail message base defined
  138.                                      by index n.      
  139.         FQuery nn.MSG n              Reprocesses single EchoMail
  140.                                      message file nn in the EchoMail
  141.                                      base defined by index n. 
  142.       NetMail: (MSG Version ONLY)
  143.  
  144.         FQuery NET fullpathname myaddress
  145.                                      Processes specified netmail message
  146.                                      to the address specified.
  147.         FQuery NET fullpathname myaddress RESCAN
  148.                                      REscans specified netmail message
  149.                                      to the address specified.   
  150.  
  151.         FQuery NET fullpathname myaddress REPROC
  152.                                      Reprocesses scans the specified netmail
  153.                                      message to the address specified.   
  154.  
  155.  
  156.       Packets:  
  157.         
  158.         FQuery LIST output_file_from_FQscan
  159.         
  160.  
  161.  
  162.     FQuery parses the subject field of each message for one or more of the
  163. following.
  164.  
  165.   ECHOMAIL SUBJECT line parameters:
  166.  
  167.   %           - user request that response be sent via netmail
  168.                 MUST be followed by a space
  169.  
  170.   keyword     - single word preceded by a / with no intervening spaces
  171.                 keywords will be ignored if thay are shorter than
  172.                 MINKCHAR
  173.                 keywords found in IGNORE_KEYS will also be ignored.
  174.  
  175.   description - string enclosed in double-quotes
  176.                 MUST be more than one word
  177.  
  178.   filename    - single word, no spaces, double-quotes or preceding /
  179.                 filespecs will be ignored if they are shorter than
  180.                 MINFCHAR.
  181.                 if an asterix '*' is found in a filename field, it and
  182.                 all following characters are removed and replaced
  183.                 internally by Amiga pattern matching.
  184.  
  185.   The  configuration  for  each  echo allows defining the minimum number of
  186. characters  required for both keywords and filespecs.  For both, this value
  187. should NEVER be less than 3.
  188.  
  189.  
  190.     Designated Reply Echo:
  191.   Some  echos  do  not  permit filefind programs to post responses, in that
  192. case,  the  reply  may be either posted in the designated filefind echo for
  193. the  same FTN (Fidonet Technology Netwrok, such as FidoNET and AmigaNET) or
  194. the filefind echo of ANOTHER FTN, or routed via netmail.
  195.  
  196.     Second Reply:
  197.   If  a  user  REPLIES to an FQuery response that indicates there were more
  198. matches found than were posted, a Second Reply will be posted or routed via
  199. netmail  with  the  full  match  listing.   Replies  are  not  processed in
  200. echos which have designated filefind reply echos.
  201.  
  202.     FQuery  searchs  the  defined  filelist  for matches to each query, and
  203. posts  a  Fquery  Response  by  writing  an  echomail PACKET in the defined
  204. INBOUND  directory  for that echo.  If an IMPORT command is defined, FQuery
  205. will  execute that command to import it's responses to the defined echomail
  206. TAGNAME.
  207.  
  208.     NETMAIL SUBJECT line parameters:
  209.   FQuery  also  accepts and processes NETMAIL queries that are addressed to
  210. FQuery  ONLY.   In addition to the above Query formats, FQuery also accepts
  211. the  following  commands.   Please note that no queries will be accepted or
  212. processed if a % command is in the subject field.  Only the first % command
  213. is processed,anything following it will be ignored.
  214.  
  215.   %help       - netmail only, returns this help text, the ABOUT of the
  216.                 the site and a list of MAGIC freqable names.
  217.   %about      - netmail only, returns the ABOUT of the site and a full
  218.   %magic        list of MAGIC names.
  219.   %newfiles   - netmail only, returns the NEWFILES list of the site
  220.   %new          via netmail.
  221.   %report <tagname> 
  222.               - sends a configuration report for echo <tagname>
  223.    
  224.  
  225.     FQuery  posts  a netmail Response by writing either a 4D or 5D echomail
  226. OUT  packet  file  in  the  defined  outbound directory.  It is the sysop's
  227. responsibilty to pack/route or crash the response.
  228.  
  229.  
  230.     Packet Scanning:
  231.  
  232.     FQscan  is  a  utility  that  scan EchoMail packets for messages to any
  233. configured FileFind program name.  FQscan creates an output file containing
  234. all  pertainent information from such messages (tagname, from, to, subject,
  235. date, origin address, msgid, fmpt etc) in any of the configured echos or in
  236. netmail.   Only  packets  from  sites  defined  in  FQ.cfg will be scanned.
  237. Packets  many  be scanned before importing, or alternativly,if one backs up
  238. inbound  mail, after importing.  The FQscan output file is always opened in
  239. append  mode  if  it exists, therefore, one can call FQuery LIST via a cron
  240. event  once  a  day.   FQuery  deletes  FQscan's  output  file  when it has
  241. completed processing it.
  242.  
  243.     Since  FQscan  is limited to sites that you configure, NetMail scanning
  244. would be limited to only those netmail messages found in packets from
  245. configured sites.   IF the scanned packet contains NetMail messages to FQuery,
  246. they  will be included in the output file, unless you set NONETSCAN to TRUE
  247. in  FQ.cfg.  In order to be able to process ALL netmail messages to FQuery,
  248. you  must  make  other  arrangments  to scan your NetMail.  This limitation
  249. applies only to the PKT version of FQuery,
  250.  
  251.     In  my  OWN  setup, I use FQueryP with NONETSCAN set TRUE and my NetMGR
  252. calls FQUERYM to handle netmail queries.
  253.  
  254.     FQscan  has  been  found  to  be  faster  than PktDump 1.10, by Charles
  255. Conlow  (which  I consider to be _the_ benchmark for both packet compliance
  256. and  scanning)  even  though  it  does  more  (ie, parseing fields, finding
  257. address in Originline etc..).
  258.  
  259.   The format of FQscan's output file is as follows:
  260.  
  261.   tagname|toname|fromname|subject|msgdate|morg|msgid|fmpt
  262.  
  263.   Each field is separated by a '|' character.
  264.  
  265.   Description of fields:
  266.  
  267.   tagname   - the Area: tagname of the echo
  268.               should be set to NETMAIL if a netmail message.
  269.   toname    - the full text of the To: field of the message
  270.   fromname  - the full text of the From: field of the message
  271.   subject   - the full text of the Subject: field of the message
  272.   msgdate   - the full text of the creation date field of the message
  273.   morg      - the address listed in the Origin: line if an echomail message
  274.               or the origin address in the INTL: line if a NetMail message
  275.   msgid     - the full text following the MSGID: line, if found
  276.   fmpt      - the full text following the FMPT line, if found 
  277.               (applies to netmail only)
  278.  
  279.   Any item not found is left blank.
  280.   If both morg and msgid are blank, a netmail response is not possible.
  281.  
  282.     The  example  script,  ScanPkts,  demonstrates  one  method of scanning
  283. backed-up  packets.   It  is  left  up to the user exactly how he will scan
  284. packets, but here are a few suggestions:
  285.  
  286.     1  -  If  inbound  packets  are backed up, use the script ScanPkts as a
  287. DAILY cron event at 11:58.
  288.  
  289.     ScanPkts:
  290.     ; MBACK:inhold is MY inbound packet backup directory,     
  291.     list MBACK:INHOLD/#?.PKT SINCE TODAY LFORMAT "rx mail:rexx/fqscan %s%s"
  292.             TO T:fqscan.cmd
  293.     execute T:fqscan.cmd
  294.     delete T:fqscan.cmd
  295.     IF EXISTS log:fqlist        ; name of output file in FQscan.cfg
  296.       FQUERYP LIST LOG:FQLIST
  297.     ENDIF
  298.  
  299.  
  300.     2  - Export the echos to scan to an unused point, copying these packets
  301. to  a  special directory where they can be scanned by FQscan.  Make sure to
  302. delete these packets after scanning.
  303.  
  304.  
  305.     3 - Your tosser may have its own message filter. If it can duplicate
  306. the output listed above, use it.
  307.  
  308.     The  example  script,  ScanPkts,  demonstrates  one  method of scanning
  309. backed-up packets.
  310.  
  311.  
  312.     EchoMail Message Scanning:
  313.  
  314.     SCAN is defined to mean that the message has been examined to see if it
  315. is addressed to ALLFIX, FILEFIND, FILEQUERY or FQUERY.
  316.  
  317.     PROC is defined to mean that such a message has been processed.
  318.  
  319.     FQuery  marks  a MSG in two ways.  
  320.     Firstly;  to indicate that it has been scanned, the PURE bit of the msg
  321.               FILE  attributes  is set as the SCAN flag.  
  322.     Secondly; to indicate it has been processed, the normally unused bit 10
  323.               of the MSG attributes is set as the PROC flag.
  324.  
  325.     After scanning, the RECD attribute of the MSG is also set.
  326.  
  327.     FQuery  sorts  MSGs in reverse order to find the highest message in the
  328. echobase.   It  scans  the  message in reverse order, checking the pure bit
  329. (SCANNED).   If  RESCAN is not enabled, FQuery will stop processed the echo
  330. base  when  it  encounters an already scanned messaage.  If the message has
  331. not been scanned, FQuery then checks if the message is a file query and the
  332. PROC  flag  has  not  been  set.   If  REPROC is enabled, the PROC flag is
  333. ingnored and the message is re-processed.
  334.  
  335.     Query Processing:
  336.  
  337.     FQuery  uses  the  defined  fileslist and the standard AmigaDos command
  338. Search,  for the processing of all search queries.  
  339.  
  340.     If an optional freqlist is defined, that list will be used for FILESPEC
  341. queries.   A  freq  list  is  NOT  a requirement for any compliant FileFind
  342. program.   If  the  optional  freqlist  is  defined,  FQuery  uses the fast
  343. freqlister searcher FSearch by Frederic Morin (FSearch is also used by RFS,
  344. RFH.  MRFH and TRFH freq handlers and a number of other utilities).  FQuery
  345. obtains  the  actual  size,  date and description of matched files from the
  346. filenote.  It then formats and wordwraps the response message.
  347.  
  348.  
  349.     Response Message:
  350.  
  351.     In  order  to  meet  both  the  rules  of  the various search echos and
  352. limitations of various msdos tossers, FQuery places some limitations on its
  353. respose messages.
  354.  
  355.     If  the list of matches is greater than the maximum bytes permitted for
  356. a  matchlist  in the echo (max:60k), Fquery will post a message to the user
  357. to  indicate that his query may have been too ambiguous and inviting him to
  358. freq or DL the MAGIC name FILES for a full list.
  359.  
  360.     If  the  list  of  matches  is  greater  than the defined matchlist per
  361. message  for  the echo, it will be split into multiple messages.  Each will
  362. have a "Part n/n" text added.  The subsequent messages will not include the
  363. ABOUT  info  of the site.  This prevents the subsequent messages from being
  364. considered as Dupes by sites running header crc dupe checkers.
  365.  
  366.   If  the  number of messages is greater than the maximum postable messages
  367. per query for the echo, and NETRESPONSE has been enabled, they will be sent
  368. as  NetMail,  otherwise the user will be informed that his request may have
  369. been too amibiguous.
  370.  
  371.     If  the  site's  ABOUT  file  is greater than the maximum system header
  372. lines for the echo, the remainder will NOT be posted.  A note will be added
  373. to the response indicated this, and the user will be either invited to Freq
  374. or  DL  the  MAGIC name MAGIC, for a full list of magic names.  If NETABOUT
  375. has been enabled, the full ABOUT file will be sent by routed netmail.
  376.  
  377.     The above limitations do not apply to NetMail queries.
  378.  
  379.     When  a response is split into multiple messages, each message is given
  380. both a unique Subject field and a unique MSGID:.  This because some tossers
  381. may use either or both for dupe detection.
  382.  
  383.     Bugs:
  384.  
  385.     Bugs  may  become  evident if your config differs from mine as shown in
  386. MyShowCfg.  Please let me know as soon as possible.
  387.  
  388.     Credits:
  389.  
  390.     FQueryM,  FQueryP,  FQscan,  FQCheckList  adn  FQFixList are written in
  391. ARexx  and require no additional libraries, except when compiled.  They are
  392. coded  is  such  a  manner  as  to  be  compilable (except for FQScan) with
  393. RexxPlus  without error or warnings, except where such errors are generated
  394. by the user during installation.
  395.  
  396.     FQuery  and  FQscan  were  developed by Robert Williamson and are based
  397. upon  parts of NetMGR, AreaMGR, Smsg, Write_PKT, FTNsort, ScanPKT and other
  398. tools  by  the  same  author.   Those  tools may have credits listing other
  399. authors who provided inspiration, code examples or other input.
  400.  
  401.     Fsearch and FQsearch were designed by Robert Williamson and coded in c
  402. by Fredric Morin.
  403.  
  404.